---
description: Deploy Hasura GraphQL Engine with Docker
keywords:
  - hasura
  - docs
  - deployment
  - docker
  - docker networking
sidebar_position: 3
sidebar_label: Using Docker
---

import LatestRelease from '@site/src/components/LatestRelease';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# Run Hasura GraphQL Engine Using Docker

## Introduction

This guide will help you deploy the Hasura GraphQL Engine and a Postgres database to store its Metadata using Docker
Compose.

## Deploying Hasura using Docker

### Prerequisites

- [Docker](https://docs.docker.com/install/)
- [Docker Compose](https://docs.docker.com/compose/install/)

### Step 1: Get the docker-compose file

The [hasura/graphql-engine/install-manifests](https://github.com/hasura/graphql-engine/tree/stable/install-manifests)
repo contains all installation manifests required to deploy Hasura anywhere. Get the docker compose file from there:

```bash
# in a new directory run
wget https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-compose/docker-compose.yaml
# or run
curl https://raw.githubusercontent.com/hasura/graphql-engine/stable/install-manifests/docker-compose/docker-compose.yaml -o docker-compose.yml
```

### Step 2: Run Hasura GraphQL Engine

The following command will run Hasura GraphQL Engine along with a Postgres database to store its Metadata.

```bash
$ docker compose up -d
```

Check if the containers are running:

```bash
$ docker ps

CONTAINER ID IMAGE                 ... CREATED STATUS PORTS          ...
097f58433a2b hasura/graphql-engine ... 1m ago  Up 1m  8080->8080/tcp ...
b0b1aac0508d postgres              ... 1m ago  Up 1m  5432/tcp       ...
```

## Securing the GraphQL endpoint {#docker-secure}

To make sure that your GraphQL endpoint and the Hasura Console are not publicly accessible, you need to configure an
admin secret key.

### Run the Docker container with an admin-secret env var

```yaml {5}
graphql-engine:
  image: hasura/graphql-engine:v2.0.0
  environment:
    HASURA_GRAPHQL_METADATA_DATABASE_URL: postgres://postgres:postgrespassword@postgres:5432/postgres
    HASURA_GRAPHQL_ADMIN_SECRET: myadminsecretkey
  ...
```

:::info Note

The `HASURA_GRAPHQL_ADMIN_SECRET` should never be passed from the client to the Hasura GraphQL Engine as it would give
the client full admin rights to your Hasura instance. See [Authentication & Authorization](/auth/overview.mdx) for
information on setting up authentication.

:::

<!--
.. hiding this as it mixes auth for the data plane with auth for the control plane and might be confusing

  .. admonition:: Using collaborators as an alternative to Hasura Admin Secret sharing with Hasura Cloud
    :class: dhc

    Hasura Cloud offers Console collaborators which avoids sharing the `HASURA-ADMIN-SECRET` with those that shouldn't have unrestricted access to your project. For more information about collaborator management, see :ref:`Collaborators in Hasura Cloud <manage_project_collaborators>`.
-->

## Hasura GraphQL Engine server logs {#docker-logs}

You can check the logs of the Hasura GraphQL Engine deployed using Docker by checking the logs of the GraphQL Engine
container:

```bash
$ docker ps

CONTAINER ID IMAGE                 ... CREATED STATUS PORTS          ...
097f58433a2b hasura/graphql-engine ... 1m ago  Up 1m  8080->8080/tcp ...
b0b1aac0508d postgres              ... 1m ago  Up 1m  5432/tcp       ...


$ docker logs 097f58433a2b

{"timestamp":"2018-10-09T11:20:32.054+0000", "level":"info", "type":"http-log", "detail":{"status":200, "query_hash":"01640c6dd131826cff44308111ed40d7fbd1cbed", "http_version":"HTTP/1.1", "query_execution_time":3.0177627e-2, "request_id":null, "url":"/v1/graphql", "user":{"x-hasura-role":"admin"}, "ip":"127.0.0.1", "response_size":209329, "method":"POST", "detail":null}}
...
```

**See:**

- [https://docs.docker.com/config/containers/logging](https://docs.docker.com/config/containers/logging) for more
  details on logging in Docker.
- [Hasura GraphQL Engine logs](/deployment/logging.mdx) for more details on Hasura logs.

## Updating Hasura GraphQL Engine {#docker-update}

This guide will help you update the Hasura GraphQL Engine running with Docker. This guide assumes that you already have
Hasura GraphQL Engine running with Docker.

### Step 1: Check the latest release version

The current latest version is:

<code>
  hasura/graphql-engine:
  <LatestRelease />
</code>

All the versions can be found at:
[https://github.com/hasura/graphql-engine/releases](https://github.com/hasura/graphql-engine/releases)

### Step 2: Update the Docker image

In the `docker compose` command that you're running, update the image tag to this latest version.

For example, if you had:

```yaml
graphql-engine:
  image: hasura/graphql-engine:v1.2.0
```

you should change it to:

<pre>
  <code>
    graphql-engine:
    <br />
    {'  '}image: hasura/graphql-engine:
    <LatestRelease />
  </code>
</pre>

:::info Note

If you are downgrading to an older version of the GraphQL Engine you might need to downgrade your Metadata catalogue
version as described in [Downgrading Hasura GraphQL Engine](/deployment/downgrading.mdx)

:::

## Docker networking

Sometimes you might want to connect Hasura running in Docker with APIs (e.g. auth webhooks, Event Triggers, Remote
Schemas) that are either running outside of Docker or in a different Docker container. Depending on the setting, the
network config is different. This section shows how to connect in each of these use cases.

### Network config

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="linux" label="Linux">

<table>
  <thead>
    <tr>
      <th>Connection</th>
      <th>Config</th>
      <th>Comment</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        <strong>Hasura to API (outside Docker)</strong>
      </td>
      <td>
        <ol type="1">
          <li>
            With <code>--net=host</code>, <code>localhost:3000</code>
          </li>
          <li>
            Otherwise, <code>&lt;docker-bridge-ip&gt;:3000</code>, e.g. <code>172.17.0.1:3000</code>
          </li>
        </ol>
      </td>
      <td>
        <ol type="1">
          <li>
            Assuming the API is running on port <code>3000</code>
          </li>
          <li>
            The Docker bridge IP can be found via <code>ifconfig</code>
          </li>
        </ol>
      </td>
    </tr>
    <tr>
      <td>
        <strong>API (outside Docker) to Hasura</strong>
      </td>
      <td>
        <code>localhost:8080</code>
      </td>
      <td>
        Hasura runs on port <code>8080</code> by default
      </td>
    </tr>
    <tr>
      <td>
        <strong>Hasura to API (both in docker-compose)</strong>
      </td>
      <td>
        service name, e.g.: <code>api:3000</code>
      </td>
      <td>
        Assuming the API is running on port <code>3000</code>
      </td>
    </tr>
    <tr>
      <td>
        <strong>API to Hasura (both in docker-compose)</strong>
      </td>
      <td>
        service name, e.g.: <code>hasura:8080</code>
      </td>
      <td>
        Hasura runs on port <code>8080</code> by default
      </td>
    </tr>
    <tr>
      <td>
        <strong>Hasura to API (both running with separate docker run)</strong>
      </td>
      <td>Docker internal IP address</td>
      <td>
        Can be obtained with <code>docker inspect</code>
      </td>
    </tr>
    <tr>
      <td>
        <strong>API to Hasura (both running with separate docker run)</strong>
      </td>
      <td>Docker internal IP address</td>
      <td>
        Can be obtained with <code>docker inspect</code>
      </td>
    </tr>
  </tbody>
</table>

</TabItem>
<TabItem value="mac" label="Mac">

| Connection                                                | Config                            | Comment                                    |
| --------------------------------------------------------- | --------------------------------- | ------------------------------------------ |
| **Hasura to API (outside Docker)**                        | `host.docker.internal:3000`       | Assuming the API is running on port `3000` |
| **API (outside Docker) to Hasura**                        | `localhost:8080`                  | Hasura runs on port `8080` by default      |
| **Hasura to API (both in docker-compose)**                | service name, e.g.: `api:3000`    | Assuming the API is running on port `3000` |
| **API to Hasura (both in docker-compose)**                | service name, e.g.: `hasura:8080` | Hasura runs on port `8080` by default      |
| **Hasura to API (both running with separate docker run)** | Docker internal IP address        | Can be obtained with `docker inspect`      |
| **API to Hasura (both running with separate docker run)** | Docker internal IP address        | Can be obtained with `docker inspect`      |

</TabItem>
<TabItem value="windows" label="Windows">

| Connection                                                | Config                            | Comment                                    |
| --------------------------------------------------------- | --------------------------------- | ------------------------------------------ |
| **Hasura to API (outside Docker)**                        | `host.docker.internal:3000`       | Assuming the API is running on port `3000` |
| **API (outside Docker) to Hasura**                        | `localhost:8080`                  | Hasura runs on port `8080` by default      |
| **Hasura to API (both in docker-compose)**                | service name, e.g.: `api:3000`    | Assuming the API is running on port `3000` |
| **API to Hasura (both in docker-compose)**                | service name, e.g.: `hasura:8080` | Hasura runs on port `8080` by default      |
| **Hasura to API (both running with separate docker run)** | Docker internal IP address        | Can be obtained with `docker inspect`      |
| **API to Hasura (both running with separate docker run)** | Docker internal IP address        | Can be obtained with `docker inspect`      |

</TabItem>
</Tabs>

### Advanced

Learn more about Docker specific networking in the [Docker documentation](https://docs.docker.com/network/).
